TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/AMIGA/AMICUS/AMIBEST1.ADF/AmigaBasicStuff/AutoRequester

Text File | 1987-07-22 | 11KB | 199 lines

AutoRequester in AmigaBASIC - Ervin Thompson [70567,523]

While the AutoRequester is a fairly simple call from BASIC using the
LIBRARY functions, it does require the setup of three IntuiText structures
in order to work. This "tutorial" will show you how to create your own
AutoRequester and give a brief explanation of the structures used in the
Amiga operating system.

The IntuiText structure is perhaps one of the most commonly used
structures when programming under Intuition. For those of you unfamiliar
with the term "structure" in this context, perhaps a brief explanation
would be in order.

In many programming envoirnments the programmer places various values in
fixed memory locations in order to achieve the desired result. This may be
as simple as changing the screen color or as complex as drawing an entire
screen bit by bit.  The multitasking nature of the Amiga prohibits the use
of most fixed memory locations in favor of tables of data that the
operating system is pointed toward in order to get the data it needs to
perform a given task.  These tables of data are known as structures.  They
more often than not contain variable data of differing types.  Using the
AutoRequester as an example we'll see that a structure can contain byte
values(8 bits), word values (2 bytes or 16 bits), and longword values (4
bytes or 32 bits). The actual "byte" size of the structure is fixed -
although it's location in memory is not.  Many times the structure
contains pointers to strings or other structures.  Pointers are simply
memory locations that contain the address of data or data structures.

We'll need to "import" two functions:  the AutoRequest function from the
Intuition.library and the AllocMem function from the Exec.library. We'll
also be using the FreeMem function from the Exec.library but it returns no
value so we need not DECLARE it.  Only functions that return a value to
AmigaBASIC need be DECLAREd.  We'll be using the AllocMem& function to
allocate enough memory for each of the three IntuiText structures
AutoRequest will need. AutoRequest then takes the data we've provided in
the structures and creates a Requester we can call at will.  The Requester
prompts the user for a yes/no type answer and then returns a BOOLEAN
response to the program.

You may be asking "Why all these text structures? Can't we just PRINT
something?". It would be nice if Intuition operated so simply but it
doesn't. Many of Intuition functions require a close working relationship
with the Graphics.library to perform screen output. The IntuiText
structure is used to communicate to Intuition the what and where (and some
other info) for the text we would like to display.

Now we'll go step by step through the IntuiText structure and any related
functions. You'll notice I refer to some of the variable names differently
than you may have seen in similar "C" applications. I use TDI's Modula-2
and it doesn't allow the underline character so I'm not at all accustomed
to using it. Some of these are self-explanatory but I'll mention them
anyway.

AllocMem& and FreeMem

The IntuiText structure requires 20 bytes of memory in which to reside.
How did we determine that this was the correct byte count? You need to add
all the bytes required in the structure in order to protect this area. We
call a system function, AllocMem, which, as the name implies, allocates a
block of memory. It also returns a pointer to that block. We need the
pointer so we can create and then POKE some values into our structure. The
system also wants to know just what type of memory we are requesting. The
ClearPublic& (I stole this one) variable is assigned the value of 65537.
This tells Intuition we want the data structure to reside in public memory
and we want Intuition to clear the memory and reset all the memory
locations to a value of 0, or null. That way we start with a clean slate.
Our pointer, which we "ingeniously" called Ptr&, will be used as the
baseline in order to POKE values into the structure. If the AllocMem&
function returns a value of 0 then the system was unable to allocate
memory for the structure(s). Proper programming dictates an orderly exit
from the program if this should occur. I didn't do that in the example
program but it should be included in a "real" program.

FreeMem simply deallocates the memory we used for our structure and frees
it to the system for other uses.

The Structure

After some digging around (and getting more than a few crashes) I
discovered how the structure is "looked at" by Intuition. The first three
values - FrontPen, BackPen and DrawMode - hold one byte values. The next
two - LeftEdge and TopEdge - hold word (or two-byte) values while the
last three - ITextFont, IText (the address of our string), and NextText -
hold longword (or four- byte) values. If you add all these together you
have a total of 19. The only problem is that we can only poke word values
into even addresses and longwords must be on even 4-byte multiples. As it
turns out the last odd byte (or bytes, in some cases) is "wasted" by the
system. This comes into play in the IntuiText structure. The first three
values are single bytes so the fourth is then wasted in order to put
everything back in line.

The first three byte values we'll POKE in - FrontPen, BackPen, and
DrawMode - will control the colors of our displayed text. The FrontPen
and Backpen colors are those selected in Preferences or as altered by
your BASIC program. The DrawMode parameter - Jam2, Complement,
InverseVid, or any combination of the three - adds a special touch to our
text rendition. I've included their respective values in the program
text. The LeftEdge and TopEdge parameters tell Intuition where you want
your text displayed relative to the "containing" element. In this case
the Requester but it could be a Gadget or Window.

ItextFont is used to control the font and fontstyle rendering of the text.
I'm using the default font here and for most applications that would
suffice. Using the SetSoftStlye and related functions you can add a
little more flair to your text rendering but that would require
substantially more programming. We'll keep our "simple" Requester simple.

The SADD function is used to extract our string address. This is
recommended in the user's manual over the VARPTR function.

The last parameter, NextText, is simply a pointer to another IntuiText
structure, if you so wish. It is NOT used to link in the other two
structures we are initializing here. It is used to tie together text into a
single unit. As you can see each structure only allows for that string of
text to be printed in one color or be located at one place in the
containing element. By linking structures together we can get a little
fancier with our text.

Many other structures, such as the Gadget or reqular Requester, can be
used in your AmigaBASIC programs. There are no hard, fast rules
concerning their setup as long as you POKE the right info into the
structure. You can't, for example, POKE a word or long word into an odd
memory address (in this case AmigaBASIC will give you an error). The
texts I've been using are the ROM Kernal Manuals and the Amiga
Programmers Handbook (SYBEX). The Programmers Handbook, while being
somewhat terse at times, does include descriptions of most of the system
calls and describes the various structures used in them. The ROM Kernal
Manuals give a detailed explanation of the calls. Neither are geared
toward the BASIC programmer but once you get the hang of it you can use
them quite easily. One book that I've seen but have yet to acquire is
Advanced AmigaBASIC published by COMPUTE!. This seems to be an excellent
text. It covers a broad range of AmigaBASIC features, including a large
number of LIBRARY calls.

If you should expand your programming horizons in the future to include
one of the high level compiled languages such as C or Modula-2, I hope
this mini-tutorial will be an aid.

(NOTE: I do a "column" called WEEKLY on the Amiga BBS of Denver
(303-693-4735). The REMS were added due to TBBS's "desire" to shrink short
lines into a single line. This example program should run as written,
though.)

' This demos the Intuition "AutoRequest" function                   .

DECLARE FUNCTION AutoRequest&() LIBRARY '                           .
DECLARE FUNCTION AllocMem&() LIBRARY '                              .

' These .library files must be in the current directory or you must .
' add a "CHDIR" to the directory containing them                    .

LIBRARY "intuition.library" '                                       .
LIBRARY "graphics.library" '                                        .
LIBRARY "exec.library" '                                            .

' The following initializes the constants Intuition needs to draw the
' AutoRequester                                                     .
W& = WINDOW(7) ' Get a pointer to the current window                .
Text$ = "Display This Requester Again?"+CHR$(0) '                   .
PosText$ = "Yesiree, Bob"+CHR$(0) '                                 .
NegText$ = "Noway, Jack"+CHR$(0) '                                  .
w% = 300 ' the width of our Requester                               .
h% = 50 ' the height                                                .
PFlags& = 0 ' These can be used to let Intuition know which other   .
NFlags& = 0 ' events, such as inserting a disk, will also satisfy   .
            ' the Requester                                         .

'this is is simpler than using three separate IntuiText structures  .
CALL SetTextStructure(Text&,0,1,1,25,5,Text$) '                     .
CALL SetTextStructure(PText&,0,1,1,6,3,PosText$) '                  .
CALL SetTextStructure(NText&,0,1,1,6,3,NegText$) '                  .

DisplayRequester: '                                                 .
bool = (AutoRequest&(W&,Text&,PText&,NText&,PFlags&,NFlags&,W%,H%))'.
IF bool = 1 THEN GOTO DisplayRequester '                            .
IF bool = 0 THEN '                                                  .
  CALL FreeMem(Text&,20)  ' This deallocates the memory for         .
  CALL FreeMem(PText&,20) ' the IntuiText structures                .
  CALL FreeMem(NText&,20) '                                         .
END IF '                                                            .
END '                                                               .

' This is the IntuiText structure                                   .
SUB SetTextStructure(Ptr&,fp%,bp%,dm%,x%,y%,strng$) STATIC '        .
  ClearPublic& = 65537& '                                           .
  Ptr& = AllocMem&(20,ClearPublic&) ' This is the "Question"        .
  IF Ptr& <> 0 THEN '                                               .
    POKE(Ptr&),fp%   ' FrontPen (value = 1-4)                       .
    POKE(Ptr&+1),bp% ' BackPen  (value = 1-4)                       .
    POKE(Ptr&+2),dm% ' DrawMode (1=Jam2,2=Complement,4=InverseVid)  .
    POKEW(Ptr&+4),x% ' LeftEdge                                     .
    POKEW(Ptr&+6),y% ' TopEdge                                      .
    POKEL(Ptr&+8),0  'ITextFont (0 = default font)                  .
    POKEL(Ptr&+12),SADD(strng$) ' IText (address of our string)     .
    POKEL(Ptr&+16),0 ' NextText                                     .
  END IF '                                                          .
END SUB '                                                           .